Troubleshooting & FAQ

This document addresses common issues, error messages, and solutions when working with Pepvoid Builder.

Common Issues & Solutions

1. `Permission denied` while mounting filesystems or extracting a stage archive

Cause: Some real-mode operations need root privileges. Real-mode stage archive extraction explicitly requires root; non-root builds can use supported PRoot execution for target commands when a verified PRoot binary is available.
Solution: Run with sudo when the requested operation needs mounts or privileged extraction, or disable --tmpfs if the permission error comes from mounting the work directory:
```
sudo python3 cli.py x86_64 --mode real
```

2. Disk image creation fails because a host utility is missing

Cause: Real disk image builds use utilities such as parted, mke2fs, mkfs.fat, mcopy, and, for VM formats, qemu-img. Image construction writes filesystem images directly and does not require loop devices.
Solution: Install the missing host utilities for the selected format and architecture, then rerun the build. Use --mode mock only to check configuration and output routing; it does not validate image bootability.

3. Cross-architecture builds fail to execute commands inside chroot

Cause: QEMU user emulators (qemu-user-static) or binfmt_misc kernel module are not configured on the host machine.
Solution: Run the host setup helper script:
```
sudo ./setup_host_build_env.sh
```

4. `xorriso reported an exit error/crash`

Cause: Missing xorriso utility or corrupted efiboot.img.
Solution: Install xorriso on your host machine (xbps-install -S xorriso or apt-get install xorriso).

5. `ConfigValidationFailed` error on `--check`

Cause: Referenced desktop, kernel, or bootloader profile JSON file does not exist in configs/.
Solution: Check spelling of profile names or verify file path in configs/desktops/ or configs/architectures/.

Log Inspection

Detailed build logs are written to workdir/logs/void_builder.log and printed to the console. If the work directory is not writable, the logger tries ~/.cache/void-builder/logs/, then a temporary directory.

python3 cli.py x86_64 -v --mode mock